Programming Manual Chap. 01
About the Development Environment To gain access to the development environment, you need a free account on the Wild Pockets web site. This account gives you access to our development environment, which is called the builder. Your free account also gives you access to a folder on our file server where you can store your scripts, art files, and other assets. Once you have created your account, select Builder (the development environment) from the website menu. To use the builder, you will need to install the Wild Pockets plugin if you have not done so already. The Server Folder and the Local Folder Wild Pockets provides every account-holder with a server folder on our file server. This is your main repository for scripts, art assets, and other game-related files. The builder also creates a local folder on your hard drive. These two folders are meant to be mirror-images of each other - they will usually contain identical files. You can view the two folders by clicking on the Folders menu in the builder, and select Open Server Folder and Open Local Folder. When using Wild Pockets, scripts are created by using your programmer's editor to save them into the local folder. Then, a synchronization tool we provide is used to "mirror" the script to the server folder. Models are created the other way around: the exporter writes to the server folder. Then, the synchronization tool is used to "mirror" the file to the local folder. You don't need to worry at all about which "side" (local or server) a file is written to. The development environment will look on both sides - server and local. It is smart enough to find the most-recent version, regardless of which side it is stored on. Likewise, the synchronization tool is smart enough to mirror all files, regardless of which "side" they were saved to. It may take a little while to get comfortable with the idea that you can write a file to either side, and things will just work. But that is indeed how it functions. In fact, the only reason to worry about which side a file is on is for sharing: your game needs to be entirely on the server if you want other people to be able to play it. At any time, you can use the menu item Folders/Sync username to copy all source files to both sides. The synchronization tool is described in greater detail in the chapter on the file server. For the purposes of this quick start, you won't need the synchronization tool. Instead, you'll just rely on the development environment's ability to find files regardless of which side they're on. The Two Main Files Every game in Wild Pockets consists of at least two files: a Lua script file for the main program, and a scene file describing the initial state of the world. The lua script contains the code of your world. The scene file contains the initial object layout. The scene file must also contain the name of the Lua script file. You will be starting by making a hello-world game. This will consist of a script file called HelloScript.lua, and a scene file called HelloGame.scene. Creating the Script File To create the Lua script file, open your local folder. Using your favorite programmer's editor, create a file in this directory called HelloScript.lua. (Make sure you have Windows Explorer configured to not hide file extensions, otherwise you may accidentally create HelloScript.lua.txt, which is not correct.) Put the following code into HelloScript.lua: function onSceneStart() print("Hello World") end Creating the Scene File In addition to being a general-purpose development environment, the builder is also an editor for scene files. It always has a scene open for editing. By default, it opens the standard scene, consisting of two blue boxes, a sky, and some ground. You probably already have the standard scene open for editing. If you haven't already done so, open the builder, which will open the standard scene. Then, insert the filename of HelloScript.lua into this scene. Do this by selecting File/Global Properties from the menubar. Click on the "Script Properties" tab. You will see that the scene already has a main script, called "wild pockets team/defaultSceneScript" (which is a little too wide to fit in the window, so you probably only see "wild pockets team/" or the like). Click the "..." button next to this filename to replace it. In the explorer that pops up, select "HelloScript.lua" and click the "Open" button. Now that you have configured the scene's script, you need to save the scene. Using the File menu, select File/Save As..., and store it as "username/HelloGame.scene". Testing your Game You are now ready to test your game. Select 'Begin Test' from the 'Test' menu. When you test it, the unsupported cube will fall to the ground. This is the only obvious behavior. However, if you use the little icon on the right to open the debugging console, you will see the words 'Hello World' inside the console. Congratulations, you have written your first game. From this point forward, you can edit both the Lua script file and the scene file. When you do, you will need to close and reopen the testing window. If you do not, it will not notice changes to the scene. The Autosave File Whenever you hit 'Test', the development environment writes out your saved-game file to an autosave location. If you should ever experience a crash in the development environment, there is a good chance that this autosave might contain a great deal of your work. You can load the autosave from the development environment's File-Open menu under the name "__tp__.scene".